home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / SCSL / dtgsy2.z / dtgsy2
Encoding:
Text File  |  2002-10-03  |  9.1 KB  |  265 lines
  1.  
  2.  
  3.  
  4. DDDDTTTTGGGGSSSSYYYY2222((((3333SSSS))))                                                          DDDDTTTTGGGGSSSSYYYY2222((((3333SSSS))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      DTGSY2 - solve the generalized Sylvester equation
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      SUBROUTINE DTGSY2( TRANS, IJOB, M, N, A, LDA, B, LDB, C, LDC, D, LDD, E,
  13.                         LDE, F, LDF, SCALE, RDSUM, RDSCAL, IWORK, PQ, INFO )
  14.  
  15.          CHARACTER      TRANS
  16.  
  17.          INTEGER        IJOB, INFO, LDA, LDB, LDC, LDD, LDE, LDF, M, N, PQ
  18.  
  19.          DOUBLE         PRECISION RDSCAL, RDSUM, SCALE
  20.  
  21.          INTEGER        IWORK( * )
  22.  
  23.          DOUBLE         PRECISION A( LDA, * ), B( LDB, * ), C( LDC, * ), D(
  24.                         LDD, * ), E( LDE, * ), F( LDF, * )
  25.  
  26. IIIIMMMMPPPPLLLLEEEEMMMMEEEENNNNTTTTAAAATTTTIIIIOOOONNNN
  27.      These routines are part of the SCSL Scientific Library and can be loaded
  28.      using either the -lscs or the -lscs_mp option.  The -lscs_mp option
  29.      directs the linker to use the multi-processor version of the library.
  30.  
  31.      When linking to SCSL with -lscs or -lscs_mp, the default integer size is
  32.      4 bytes (32 bits). Another version of SCSL is available in which integers
  33.      are 8 bytes (64 bits).  This version allows the user access to larger
  34.      memory sizes and helps when porting legacy Cray codes.  It can be loaded
  35.      by using the -lscs_i8 option or the -lscs_i8_mp option. A program may use
  36.      only one of the two versions; 4-byte integer and 8-byte integer library
  37.      calls cannot be mixed.
  38.  
  39. PPPPUUUURRRRPPPPOOOOSSSSEEEE
  40.      DTGSY2 solves the generalized Sylvester equation:
  41.                  A * R - L * B = scale * C                (1)
  42.                  D * R - L * E = scale * F,
  43.  
  44.      using Level 1 and 2 BLAS. where R and L are unknown M-by-N matrices, (A,
  45.      D), (B, E) and (C, F) are given matrix pairs of size M-by-M, N-by-N and
  46.      M-by-N, respectively, with real entries. (A, D) and (B, E) must be in
  47.      generalized Schur canonical form, i.e. A, B are upper quasi triangular
  48.      and D, E are upper triangular. The solution (R, L) overwrites (C, F). 0
  49.      <= SCALE <= 1 is an output scaling factor chosen to avoid overflow.
  50.  
  51.      In matrix notation solving equation (1) corresponds to solve Z*x =
  52.      scale*b, where Z is defined as
  53.  
  54.             Z = [ kron(In, A)  -kron(B', Im) ]             (2)
  55.                 [ kron(In, D)  -kron(E', Im) ],
  56.  
  57.      Ik is the identity matrix of size k and X' is the transpose of X.
  58.      kron(X, Y) is the Kronecker product between the matrices X and Y.  In the
  59.      process of solving (1), we solve a number of such systems where Dim(In),
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. DDDDTTTTGGGGSSSSYYYY2222((((3333SSSS))))                                                          DDDDTTTTGGGGSSSSYYYY2222((((3333SSSS))))
  71.  
  72.  
  73.  
  74.      Dim(In) = 1 or 2.
  75.  
  76.      If TRANS = 'T', solve the transposed system Z'*y = scale*b for y, which
  77.      is equivalent to solve for R and L in
  78.  
  79.                  A' * R  + D' * L   = scale *  C           (3)
  80.                  R  * B' + L  * E'  = scale * -F
  81.  
  82.      This case is used to compute an estimate of Dif[(A, D), (B, E)] =
  83.      sigma_min(Z) using reverse communicaton with DLACON.
  84.  
  85.      DTGSY2 also (IJOB >= 1) contributes to the computation in STGSYL of an
  86.      upper bound on the separation between to matrix pairs. Then the input (A,
  87.      D), (B, E) are sub-pencils of the matrix pair in DTGSYL. See STGSYL for
  88.      details.
  89.  
  90.  
  91. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  92.      TRANS   (input) CHARACTER
  93.              = 'N', solve the generalized Sylvester equation (1).  = 'T':
  94.              solve the 'transposed' system (3).
  95.  
  96.      IJOB    (input) INTEGER
  97.              Specifies what kind of functionality to be performed.  = 0: solve
  98.              (1) only.
  99.              = 1: A contribution from this subsystem to a Frobenius norm-based
  100.              estimate of the separation between two matrix pairs is computed.
  101.              (look ahead strategy is used).  = 2: A contribution from this
  102.              subsystem to a Frobenius norm-based estimate of the separation
  103.              between two matrix pairs is computed. (DGECON on sub-systems is
  104.              used.)  Not referenced if TRANS = 'T'.
  105.  
  106.      M       (input) INTEGER
  107.              On entry, M specifies the order of A and D, and the row dimension
  108.              of C, F, R and L.
  109.  
  110.      N       (input) INTEGER
  111.              On entry, N specifies the order of B and E, and the column
  112.              dimension of C, F, R and L.
  113.  
  114.      A       (input) DOUBLE PRECISION array, dimension (LDA, M)
  115.              On entry, A contains an upper quasi triangular matrix.
  116.  
  117.      LDA     (input) INTEGER
  118.              The leading dimension of the matrix A. LDA >= max(1, M).
  119.  
  120.      B       (input) DOUBLE PRECISION array, dimension (LDB, N)
  121.              On entry, B contains an upper quasi triangular matrix.
  122.  
  123.      LDB     (input) INTEGER
  124.              The leading dimension of the matrix B. LDB >= max(1, N).
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. DDDDTTTTGGGGSSSSYYYY2222((((3333SSSS))))                                                          DDDDTTTTGGGGSSSSYYYY2222((((3333SSSS))))
  137.  
  138.  
  139.  
  140.      C       (input/output) DOUBLE PRECISION array, dimension (LDC, N)
  141.              On entry, C contains the right-hand-side of the first matrix
  142.              equation in (1).  On exit, if IJOB = 0, C has been overwritten by
  143.              the solution R.
  144.  
  145.      LDC     (input) INTEGER
  146.              The leading dimension of the matrix C. LDC >= max(1, M).
  147.  
  148.      D       (input) DOUBLE PRECISION array, dimension (LDD, M)
  149.              On entry, D contains an upper triangular matrix.
  150.  
  151.      LDD     (input) INTEGER
  152.              The leading dimension of the matrix D. LDD >= max(1, M).
  153.  
  154.      E       (input) DOUBLE PRECISION array, dimension (LDE, N)
  155.              On entry, E contains an upper triangular matrix.
  156.  
  157.      LDE     (input) INTEGER
  158.              The leading dimension of the matrix E. LDE >= max(1, N).
  159.  
  160.      F       (input/output) DOUBLE PRECISION array, dimension (LDF, N)
  161.              On entry, F contains the right-hand-side of the second matrix
  162.              equation in (1).  On exit, if IJOB = 0, F has been overwritten by
  163.              the solution L.
  164.  
  165.      LDF     (input) INTEGER
  166.              The leading dimension of the matrix F. LDF >= max(1, M).
  167.  
  168.      SCALE   (output) DOUBLE PRECISION
  169.              On exit, 0 <= SCALE <= 1. If 0 < SCALE < 1, the solutions R and L
  170.              (C and F on entry) will hold the solutions to a slightly
  171.              perturbed system but the input matrices A, B, D and E have not
  172.              been changed. If SCALE = 0, R and L will hold the solutions to
  173.              the homogeneous system with C = F = 0. Normally, SCALE = 1.
  174.  
  175.      RDSUM   (input/output) DOUBLE PRECISION
  176.              On entry, the sum of squares of computed contributions to the
  177.              Dif-estimate under computation by DTGSYL, where the scaling
  178.              factor RDSCAL (see below) has been factored out.  On exit, the
  179.              corresponding sum of squares updated with the contributions from
  180.              the current sub-system.  If TRANS = 'T' RDSUM is not touched.
  181.              NOTE: RDSUM only makes sense when DTGSY2 is called by STGSYL.
  182.  
  183.      RDSCAL  (input/output) DOUBLE PRECISION
  184.              On entry, scaling factor used to prevent overflow in RDSUM.  On
  185.              exit, RDSCAL is updated w.r.t. the current contributions in
  186.              RDSUM.  If TRANS = 'T', RDSCAL is not touched.  NOTE: RDSCAL only
  187.              makes sense when DTGSY2 is called by DTGSYL.
  188.  
  189.      IWORK   (workspace) INTEGER array, dimension (M+N+2)
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. DDDDTTTTGGGGSSSSYYYY2222((((3333SSSS))))                                                          DDDDTTTTGGGGSSSSYYYY2222((((3333SSSS))))
  203.  
  204.  
  205.  
  206.      PQ      (output) INTEGER
  207.              On exit, the number of subsystems (of size 2-by-2, 4-by-4 and 8-
  208.              by-8) solved by this routine.
  209.  
  210.      INFO    (output) INTEGER
  211.              On exit, if INFO is set to =0: Successful exit
  212.              <0: If INFO = -i, the i-th argument had an illegal value.
  213.              >0: The matrix pairs (A, D) and (B, E) have common or very close
  214.              eigenvalues.
  215.  
  216. FFFFUUUURRRRTTTTHHHHEEEERRRR DDDDEEEETTTTAAAAIIIILLLLSSSS
  217.      Based on contributions by
  218.         Bo Kagstrom and Peter Poromaa, Department of Computing Science,
  219.         Umea University, S-901 87 Umea, Sweden.
  220.  
  221.  
  222. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  223.      INTRO_LAPACK(3S), INTRO_SCSL(3S)
  224.  
  225.      This man page is available only online.
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.